Skip to content

docs: comprehensive documentation gap audit report#972

Closed
cursor[bot] wants to merge 1 commit into
mainfrom
cursor/sentry-cli-documentation-gaps-04a7
Closed

docs: comprehensive documentation gap audit report#972
cursor[bot] wants to merge 1 commit into
mainfrom
cursor/sentry-cli-documentation-gaps-04a7

Conversation

@cursor
Copy link
Copy Markdown
Contributor

@cursor cursor Bot commented May 18, 2026

Summary

This PR adds a comprehensive documentation gap report (DOCUMENTATION_GAPS.md) produced by auditing the full repository — cross-referencing every command implementation in src/commands/ against the documentation in README.md, DEVELOPMENT.md, docs/src/content/docs/, and docs/src/fragments/commands/.

Methodology

  1. Read all root documentation files (README, DEVELOPMENT.md, AGENTS.md, doc site pages)
  2. Read all 21 command documentation fragments under docs/src/fragments/commands/
  3. Read every command implementation file (src/commands/*/) extracting flags, descriptions, and positional args
  4. Read installation/distribution code (install script, .craft.yml, package.json, setup/upgrade)
  5. Read auth/configuration code and plugin/skills system
  6. Cross-referenced findings into a structured gap report

Key Findings

The report is organized into 10 sections (A–J):

  • A. Undocumented commandsdashboard revisions and dashboard restore have no documentation
  • B. Undocumented flags — 30+ non-hidden flags across commands lack documentation (notably --spans, --timeout, --offline, --method, sourcemap flags)
  • C. Missing usage examples — Several commands lack standalone examples
  • D. Stale descriptions — Minor inconsistencies only (generated system keeps things in sync)
  • E. Skill generator routes — No gaps (automatic 1:1 mapping)
  • F. Installation gaps — Node.js ≥22.12 requirement not documented for npm users; install script flags undocumented
  • G. Undocumented env varsSENTRY_RELEASE, SENTRY_NO_CACHE, SENTRY_PLAIN_OUTPUT, and others missing from config page
  • H. Auth/self-hosted gaps--url flag and trust anchor behavior undocumented
  • I. Plugin/skills gaps — Cursor support description inconsistent between docs
  • J. README drift — Minor (yarn missing from README, redundant dev commands)

Top 5 Priorities

  1. Add Node.js ≥22.12 requirement to getting-started docs
  2. Document --url flag for self-hosted login
  3. Add dashboard revisions/restore documentation
  4. Document sourcemap upload flags (--dist, --ignore, etc.)
  5. Document sentry cli defaults headers/ca-cert in self-hosted guide

Next Steps

This report is intended as a reference for prioritizing documentation work. Each section includes source file references so individual gaps can be addressed incrementally.

Open in Web View Automation 

Audit the full repository to cross-reference implementation code against
documentation (README.md, DEVELOPMENT.md, docs site, fragments). The report
identifies:

- Undocumented commands (dashboard revisions/restore)
- Undocumented flags across 15+ commands
- Missing usage examples
- Installation/distribution documentation gaps
- Undocumented environment variables
- Auth/self-hosted documentation gaps
- Plugin/skills system inconsistencies
- README/DEVELOPMENT.md drift

Includes a prioritized list of the top 5 most impactful fixes.

Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
@BYK
Copy link
Copy Markdown
Member

BYK commented Jun 2, 2026

Superseded by #1050, which unifies the recurring BugBot documentation audits into a single PR.

This PR only added a DOCUMENTATION_GAPS.md report and no doc fixes. That report is intentionally not committed — #1050 treats these audit reports as throwaway artifacts and gitignores them so future bot runs don't commit them. The actionable findings it surfaced (AGENTS.md tree drift, cli defaults/self-hosted gaps, etc.) are addressed directly in #1050; notably the AGENTS.md tree is removed rather than re-maintained, eliminating the root cause of these weekly audits.

Closing in favor of #1050.

@BYK BYK closed this Jun 2, 2026
BYK added a commit that referenced this pull request Jun 2, 2026
## Summary

Consolidates the four recurring Cursor BugBot **"docs:"** audit PRs into
a single set of verified fixes, and removes the *root cause* of the
repeated audits.

Supersedes and closes:
- #972 — comprehensive documentation gap audit report
- #946 — fix documentation gaps identified by automated audit
- #1043 — fix stale architecture tree and phantom `--cause` flag
- #909 — fix documentation gaps identified in comprehensive audit

## Root cause: AGENTS.md tree drift

Every one of those PRs re-fixed the **hand-maintained architecture tree
in `AGENTS.md`**. That tree drifts whenever a command or API module is
added, so the weekly audit keeps re-filing it.

The repo already generates an always-current project-structure tree into
`docs/src/content/docs/contributing.md` via
`script/generate-docs-sections.ts`. This PR **removes the duplicated
tree from `AGENTS.md`** and replaces it with a concise pointer to the
generated tree (plus `ls src/commands/` / `sentry --help`). This
eliminates the recurring audit target permanently.

## Verified fixes harvested from the audits

Each change was verified against current `main` source, not blindly
cherry-picked:

- **`issue.md`** — removed the phantom `sentry issue plan --cause 0`
example. The `--cause` flag does not exist in `plan.ts`; `plan`
automatically runs root-cause analysis (`ensureRootCauseAnalysis`) when
needed. Requirements text updated accordingly. *(from #1043)*
- **`src/lib/env-registry.ts`** — registered `SENTRY_INIT_TUI` (read at
`src/lib/init/ui/factory.ts`) so it surfaces in the generated
`configuration.md`. *(from #946)*
- **`cli.md`** — documented `sentry cli defaults headers` and `sentry
cli defaults ca-cert` (both implemented in `defaults.ts`). *(from #946)*
- **`self-hosted.md`** — documented `auth login --url` as the
recommended, trust-anchoring login method, and added a **TLS / Corporate
Proxies** section (`NODE_EXTRA_CA_CERTS` + `cli defaults
ca-cert`/`headers`). *(from #909)*
- **`getting-started.mdx` / `README.md`** — noted the **Node.js 22.15+**
requirement for npm/pnpm/yarn packages (matches `package.json` engines);
added `yarn` install + `pnpm dlx`/`yarn dlx`/`bunx` run options to the
README. *(from #909/#946)*

Regenerated skill references (`references/issue.md`,
`references/cli.md`) via `pnpm run generate:docs`.

## Discarded

- The throwaway `DOCUMENTATION_GAPS.md` / `docs/DOCUMENTATION_GAPS.md` /
`DOCUMENTATION_GAP_REPORT.md` audit artifacts are **not** committed, and
are now gitignored so future bot audits don't accidentally commit them.
- Skipped items already landed on `main` since the PRs opened (dashboard
`revisions`/`restore` examples, `configuration.md` cross-refs) and the
unverified Cursor `~/.agents` claim that #972 itself flagged as
inaccurate.

## Verification

- `pnpm run typecheck` ✅
- `pnpm run lint` ✅ (only pre-existing unrelated warning in
`formatters/local.ts`)
- `pnpm run check:fragments` ✅ (all 22 fragments valid)
- `pnpm exec vitest run test/lib test/commands test/types` ✅ (5529
passed, 9 skipped)
- Confirmed `SENTRY_INIT_TUI` appears in generated `configuration.md`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants